REST API

BindAI v0.1 includes a FastAPI-based REST API package for exposing configured BindAI applications over HTTP. The API provides a lightweight service boundary around:

Agents
Workflows
Projects
Background automation runs

The API package is:

bindai-api

It exposes capabilities from an existing BindAI application rather than replacing the underlying Python framework.

Installation

Install the API package from PyPI:

pip install bindai-api

The API package depends on the BindAI framework and uses:

FastAPI
Pydantic
Uvicorn
BindAI

The package can be used independently of the repository’s Docker configuration. For local BindAI repository development, the package is part of the workspace and can be installed through the repository’s normal uv workflow.

API Application

The main FastAPI application is exposed as:

from bindai_api import app

Serve it with Uvicorn:

uv run uvicorn bindai_api.app:app --host 0.0.0.0 --port 8000

For local development, the API is normally available at:

http://localhost:8000

FastAPI also provides its standard interactive API documentation through the running application. The API application itself does not automatically discover and configure a BindAI application. A host application can configure the application exposed by the API:

from bindai_api import configure_application

configure_application(application)

The configured application then provides the agents and runtime resources used by the API.

API Version

The current REST API uses versioned resource paths:

/api/v1

Resource endpoints therefore follow the general structure:

/api/v1/<resource>

Versioned paths provide a stable boundary for future API versions. The health endpoint is intentionally outside the versioned resource namespace:

/health

Health Check

The API provides a public health endpoint:

GET /health

Example:

curl http://localhost:8000/health

Example response:

{
  "status": "ok",
  "service": "bindai-api"
}

The health endpoint does not require authentication. It can be used for:

Local development
Docker health checks
Deployment infrastructure
Basic service monitoring

The endpoint represents API application availability. It does not perform a complete health check of configured model providers, connections, or other external services.

Authentication

Protected API endpoints require API-key authentication. Configure the API key through the environment:

BINDAI_API_KEY=your-secret-key

Clients send the key using the HTTP Authorization header:

Authorization: Bearer your-secret-key

For example:

curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/agents

The /health endpoint remains public. The v0.1 authentication implementation intentionally uses a single environment-based API key. It does not provide:

User accounts
OAuth
Persistent API-key management
Role-based access control
Multi-tenant authorization

If BINDAI_API_KEY is configured, a missing or incorrect Bearer token results in 401 Unauthorized. If BINDAI_API_KEY itself is not configured, the current authentication dependency raises a server-side configuration error rather than performing normal API-key validation. See the Authentication documentation for complete details.

Agents

The Agents API provides agent discovery and execution. Base path:

/api/v1/agents

The current agent endpoints are:

GET  /api/v1/agents
POST /api/v1/agents/{agent_name}/run
POST /api/v1/agents/{agent_name}/stream

All agent endpoints require API authentication.

List Agents

Retrieve the agents available from the configured BindAI application:

GET /api/v1/agents

Example:

curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/agents

The API resolves agents from the configured application. The API does not create a separate agent registry independent of the BindAI application. If no application has been configured, the API cannot serve application-backed resources normally.

Run an Agent

Execute an agent synchronously:

POST /api/v1/agents/{agent_name}/run

The request body contains a message:

{
  "message": "Explain how BindAI works."
}

Example:

curl \
  -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"message":"Explain how BindAI works."}' \
  http://localhost:8000/api/v1/agents/assistant/run

The response identifies the agent and contains its result. Conceptually:

{
  "agent": "assistant",
  "response": "..."
}

The exact response value depends on the configured agent and its model provider.

Agent Streaming

Agents can also be executed through the streaming endpoint:

POST /api/v1/agents/{agent_name}/stream

The request uses the same message structure:

{
  "message": "Write a short explanation of AI agents."
}

Example:

curl \
  -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"message":"Write a short explanation of AI agents."}' \
  http://localhost:8000/api/v1/agents/assistant/stream

The endpoint returns a plain HTTP streaming response using FastAPI’s StreamingResponse. The v0.1 implementation is intentionally lightweight. It is not a separate distributed streaming service and does not define persistent stream-management infrastructure. For additional details, see the Streaming documentation.

Agent Execution Flow

A typical request follows this flow:

HTTP Client
    |
    v
POST /api/v1/agents/{agent}/run
    |
    v
BindAI API
    |
    v
Configured Application
    |
    v
Agent
    |
    v
Model / Tools / Memory
    |
    v
Agent Result
    |
    v
HTTP Response

The REST API is therefore a transport boundary around the existing BindAI agent execution system.

Workflows

The Workflows API provides workflow discovery and execution. Base path:

/api/v1/workflows

The current workflow endpoints are:

GET  /api/v1/workflows
POST /api/v1/workflows/{workflow_id}/run

All workflow endpoints require API authentication.

List Workflows

Retrieve the configured workflows:

GET /api/v1/workflows

Example:

curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/workflows

The API obtains workflows from the configured BindAI workflow registry.

Run a Workflow

Execute a workflow:

POST /api/v1/workflows/{workflow_id}/run

The request body contains workflow variables:

{
  "variables": {
    "customer": "Example",
    "priority": "high"
  }
}

Example:

curl \
  -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"customer":"Example","priority":"high"}}' \
  http://localhost:8000/api/v1/workflows/research/run

The variables are added to the workflow execution context before execution. Conceptually:

HTTP Request
    |
    v
Workflow
    |
    v
ExecutionContext
    |
    v
Workflow Nodes
    |
    v
Workflow Result

Workflow Execution

Workflow execution remains part of the BindAI runtime. The API does not replace workflow orchestration. A configured workflow can use the BindAI capabilities available to it, such as:

Agents
Tools
Conditions
Loops
Parallel execution
Retry policies
Timeouts
Human tasks
Connections

The exact capabilities depend on the configured workflow.

Projects

The Projects API exposes projects configured in the current API process. Base path:

/api/v1/projects

The current project endpoints are:

GET /api/v1/projects
GET /api/v1/projects/{project_name}

All project endpoints require API authentication.

List Projects

Retrieve configured projects:

GET /api/v1/projects

Example:

curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/projects

The API returns projects configured in the current application process. The v0.1 API does not provide a persistent project-management service.

Get a Project

Retrieve a project by name:

GET /api/v1/projects/{project_name}

Example:

curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/projects/my-project

If the requested project is not configured, the API returns a not-found response.

Project Storage

The v0.1 Projects API uses an in-process project registry. It does not provide a persistent project-management database. Conceptually:

BindAI API Process
       |
       v
Configured Projects
       |
       +---- Project A
       +---- Project B
       +---- Project C

Projects therefore belong to the running API process. Applications requiring persistent project management need an external persistence layer or a future BindAI project-management implementation.

Background Runs

BindAI v0.1 exposes background automation runs through:

/api/v1/runs

The current endpoints are:

POST /api/v1/runs
GET  /api/v1/runs/{run_id}

A background run can be submitted and queried later using its run ID. All run endpoints require API authentication.

Submit a Background Run

Create a background automation run:

POST /api/v1/runs

The request identifies an automation definition:

{
  "automation_id": "daily-report",
  "input": {
    "customer": "Example"
  }
}

Example:

curl \
  -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"automation_id":"daily-report","input":{"customer":"Example"}}' \
  http://localhost:8000/api/v1/runs

A successful submission returns a run representation with HTTP 202 Accepted. The request is accepted for background execution rather than waiting for the automation to complete.

Get Run Status

Retrieve a background run:

GET /api/v1/runs/{run_id}

Example:

curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/runs/run-id

A run contains information such as:

Run ID
Automation definition ID
Definition version
Status
Input
Output
Error
Creation time
Start time
Completion time

Conceptually:

{
  "id": "run-id",
  "definition_id": "daily-report",
  "definition_version": 1,
  "status": "completed",
  "input": {},
  "output": {},
  "error": null,
  "created_at": "2026-01-01T12:00:00+00:00",
  "started_at": "2026-01-01T12:00:01+00:00",
  "completed_at": "2026-01-01T12:00:05+00:00"
}

The exact values depend on the automation execution.

Background Execution Model

The REST API delegates background automation execution to AutomationWorker. For v0.1, the worker uses an in-process thread pool. Conceptually:

API Request
    |
    v
Automation Definition
    |
    v
AutomationWorker
    |
    v
AutomationRun

The worker creates and persists an AutomationRun before submitting the execution to its thread pool. The API can therefore return the run representation without waiting for the automation to finish. The background execution model is intentionally lightweight for the initial public release. It does not require an external message broker or distributed queue.

Background Run Input

The background-run request supports an input value:

{
  "automation_id": "daily-report",
  "input": {
    "customer": "Example"
  }
}

The input is stored on the resulting AutomationRun. The current AutomationWorker implementation does not automatically pass that input as an argument to AutomationDefinition.run(). Therefore, applications should not assume that the input field is automatically delivered to the automation target. How an automation consumes input depends on the automation definition and surrounding application design.

Background Execution Limitations

Background execution in v0.1 is process-local. The worker uses a Python ThreadPoolExecutor and maintains its state and run history in process-local stores by default. This has important operational consequences. For example:

Application Process
       |
       +---- API
       |
       +---- AutomationWorker
              |
              +---- Background Run

If the process stops, in-process work can be interrupted. Running multiple API instances does not automatically create a coordinated distributed worker system:

Instance A
    |
    +---- Local worker

Instance B
    |
    +---- Local worker

These instances do not automatically coordinate their in-process execution state. Durable queue-based execution and coordinated distributed workers are planned for later releases.

API and Runtime Configuration

The API application must be configured with the BindAI application it is intended to expose. The API package provides:

from bindai_api import configure_application

Configure the application:

configure_application(application)

The configured application provides the agents and runtime resources used by the API. The REST API should therefore be considered an interface to an existing BindAI application rather than a separate agent runtime. If an application has not been configured, application-backed routes cannot operate normally.

Docker

The BindAI repository includes a Dockerfile for running the API. Build the image from the repository root:

docker build -t bindai-api .

Run the container:

docker run --rm -p 8000:8000 \
  -e BINDAI_API_KEY=your-secret-key \
  bindai-api

The API is then available at:

http://localhost:8000

Additional provider credentials can be supplied through environment variables as required by the configured application.

Docker Compose

The repository also includes Docker Compose configuration. Start the API:

docker compose up --build

Stop the services:

docker compose down

The default API port is:

A typical deployment looks like:

Client
   |
   v
Docker Compose
   |
   v
BindAI API
   |
   +---- Agents
   +---- Workflows
   +---- Projects
   +---- Automation
   |
   v
External Providers / Services

Docker Compose provides a convenient deployment foundation for local and small-scale environments. It does not turn the v0.1 background worker into a distributed queue-based system.

Environment Variables

The API authentication layer requires:

BINDAI_API_KEY

The configured BindAI application may also require provider-specific variables. Examples include:

OPENAI_API_KEY
ANTHROPIC_API_KEY
GEMINI_API_KEY
GROQ_API_KEY
OPENROUTER_API_KEY
PINECONE_API_KEY

The exact variables depend on the application’s providers, memory systems, knowledge systems, and connections. Never commit secrets to source control.

Error Responses

The API uses HTTP status codes to represent request outcomes. Examples include:

200 OK

for successful requests,

202 Accepted

for successfully submitted background runs,

401 Unauthorized

for invalid or missing API authentication, and:

404 Not Found

when a requested resource such as an agent, workflow, or project cannot be found. Application and execution failures may produce additional HTTP error responses depending on where the failure occurs. If the API itself is misconfigured, such as when BINDAI_API_KEY is missing, the current authentication dependency can raise a server-side configuration error.

API Security

The v0.1 API provides a deliberately simple authentication mechanism. When exposing the API outside a trusted local environment, deployment infrastructure should additionally consider:

HTTPS
Network access controls
Reverse proxies
Rate limiting
Request limits
Secret management
Logging
Monitoring
Process isolation

The BindAI v0.1 API does not provide a complete user-management or authorization platform. Applications requiring advanced identity and authorization can place those controls in front of the BindAI API.

API and Observability

BindAI’s event system can be used alongside the REST API. The runtime can emit structured events for areas such as:

Application lifecycle
Agent execution
Workflow execution
Node execution
Human tasks
Model requests and responses
Tool execution
Memory operations
MCP connection events

BindAI also provides an in-memory EventRecorder. The recorder can be used for:

Development
Debugging
Execution inspection
Custom logging
Application-level monitoring integrations

The current recorder is process-local and is not a persistent tracing backend. The REST API itself does not provide a hosted observability dashboard.

API Deployment Architecture

A simple BindAI API deployment can be represented as:

Client
   |
   | HTTPS
   v
Reverse Proxy / Load Balancer
   |
   v
BindAI API
   |
   +---- Agents
   |
   +---- Workflows
   |
   +---- Projects
   |
   +---- Background Runs
   |
   v
External Providers / Services

The BindAI API provides the application-level HTTP boundary. The surrounding infrastructure remains responsible for concerns such as:

TLS
Networking
Secrets
Process management
Persistent storage
Monitoring
Scaling
Backups

Scaling

The v0.1 API can be deployed behind standard HTTP infrastructure. However, horizontal scaling requires careful consideration of application state. For example:

Load Balancer
      |
      +---- API Instance A
      |
      +---- API Instance B
      |
      +---- API Instance C

API instances do not automatically share all in-process state. This is particularly important for:

Configured projects
Background execution
Runtime state
In-memory observability
Other process-local resources

Applications requiring coordinated distributed execution should introduce shared persistent infrastructure.

Distributed Background Execution

Queue-based background execution is outside the initial v0.1 API scope. A future architecture could look like:

Client
   |
   v
BindAI API
   |
   v
Persistent Queue
   |
   +---- Worker A
   +---- Worker B
   +---- Worker C
   |
   v
Persistent State

This would provide a stronger foundation for:

Durable execution
Multiple workers
Work recovery
Coordinated execution
Horizontal scaling

The current v0.1 API does not require this architecture.

Testing

The API package has its own test suite. Run the API tests with:

uv run pytest packages/bindai-api/tests -q

The complete BindAI test suite can also be run with:

uv run pytest tests -q

The API tests cover the implemented API resources and authentication behavior.

Local API Validation

A simple local validation sequence is: Start the API:

uv run uvicorn bindai_api.app:app --host 0.0.0.0 --port 8000

Check health:

curl http://localhost:8000/health

Configure the API key in the API process environment:

BINDAI_API_KEY=your-secret-key

Then test a protected endpoint:

curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/projects

This verifies API availability and authentication. Application-backed endpoints additionally require a configured BindAI application.

Current API Scope

BindAI v0.1 provides the following public REST API surface.

Health

GET /health

Agents

GET  /api/v1/agents
POST /api/v1/agents/{agent_name}/run
POST /api/v1/agents/{agent_name}/stream

Workflows

GET  /api/v1/workflows
POST /api/v1/workflows/{workflow_id}/run

Projects

GET /api/v1/projects
GET /api/v1/projects/{project_name}

Background Runs

POST /api/v1/runs
GET  /api/v1/runs/{run_id}

These endpoints form the initial public REST API surface for BindAI v0.1.

Current Limitations

The v0.1 API intentionally keeps the service layer lightweight. The current API does not provide:

Persistent project management
Persistent API-key management
User accounts
OAuth authentication
RBAC
Multi-tenancy
Distributed job queues
Durable distributed workers
Kubernetes-specific infrastructure
Hosted monitoring dashboards
Built-in billing

These capabilities can be introduced in later releases or provided by the surrounding deployment environment.

API Design Principles

The v0.1 REST API follows several simple principles:

Keep the API surface small.
Use versioned resource paths.
Reuse the existing BindAI runtime.
Keep authentication explicit.
Keep deployment infrastructure separate from application logic.
Avoid introducing persistent infrastructure unless required.
Make background execution available without requiring an external queue.
Preserve the Python API as the underlying framework interface.

The REST API provides a practical HTTP boundary without turning the BindAI core into a service-only framework.

Summary

The BindAI REST API provides an HTTP interface for running and inspecting configured BindAI applications. The main resource areas are:

BindAI API
   |
   +---- Agents
   |
   +---- Workflows
   |
   +---- Projects
   |
   +---- Background Runs

The v0.1 API provides:

Health checks
API-key authentication
Agent discovery
Agent execution
Agent streaming
Workflow discovery
Workflow execution
Project access
Background automation runs
Background run status
Docker deployment
Docker Compose deployment

The API is intentionally lightweight. It exposes capabilities already provided by the BindAI framework while leaving advanced identity, distributed execution, persistence, monitoring, and infrastructure concerns to future releases or the surrounding deployment environment. For authentication details, see the Authentication documentation. For streaming behavior, see the Streaming documentation. For background execution, see the Background Runs documentation.

​REST API

​Installation

​API Application

​API Version

​Health Check

​Authentication

​Agents

​List Agents

​Run an Agent

​Agent Streaming

​Agent Execution Flow

​Workflows

​List Workflows

​Run a Workflow

​Workflow Execution

​Projects

​List Projects

​Get a Project

​Project Storage

​Background Runs

​Submit a Background Run

​Get Run Status

​Background Execution Model

​Background Run Input

​Background Execution Limitations

​API and Runtime Configuration

​Docker

​Docker Compose

​Environment Variables

​Error Responses

​API Security

​API and Observability

​API Deployment Architecture

​Scaling

​Distributed Background Execution

​Testing

​Local API Validation

​Current API Scope

​Health

​Agents

​Workflows

​Projects

​Background Runs

​Current Limitations

​API Design Principles

​Summary

REST API

Installation

API Application

API Version

Health Check

Authentication

Agents

List Agents

Run an Agent

Agent Streaming

Agent Execution Flow

Workflows

List Workflows

Run a Workflow

Workflow Execution

Projects

List Projects

Get a Project

Project Storage

Background Runs

Submit a Background Run

Get Run Status

Background Execution Model

Background Run Input

Background Execution Limitations

API and Runtime Configuration

Docker

Docker Compose

Environment Variables

Error Responses

API Security

API and Observability

API Deployment Architecture

Scaling

Distributed Background Execution

Testing

Local API Validation

Current API Scope

Health

Agents

Workflows

Projects

Background Runs

Current Limitations

API Design Principles

Summary